home *** CD-ROM | disk | FTP | other *** search
/ HamCall (October 1991) / HamCall (Whitehall Publishing)(1991).bin / util / snr / snr.doc < prev    next >
Text File  |  1990-10-14  |  11KB  |  206 lines
  1. TITLE:         SNR.EXE             VERSION: 1.5
  2. PURPOSE:       Multi-string text Search 'N' Replace
  3. DATE:          2/23/88
  4. AUTHOR:        Thomas A. Lundin
  5.                Graphics Unlimited Inc.
  6.                3000 2nd St. N.
  7.                Minneapolis, MN 55411
  8.                (612) 588-7571
  9. DONATION:      $10 requested
  10.  
  11. DESCRIPTION:   SNR is a multi-string text search-and-replace filter. Non-text 
  12.                files can also be processed by the program, since SNR allows 
  13.                the definition of hex values in a search-and-replace equation. 
  14.                Up to 50 equations can be entered into an SNR table, each of 
  15.                which can be 140 characters in length (70 on the search side, 
  16.                and 70 on the replacement side). 
  17.  
  18. OPERATION:     The command line invocation is:
  19.  
  20.                snr [@]filename ext tablename [/d] ─┘
  21.  
  22.                1.   "filename" is any unambiguous DOS path/file name. An 
  23.                     optional at-sign (@) in front of the filename indicates 
  24.                     that multiple files are to be processed from a directory 
  25.                     list file, i.e., a file that has been created from a 
  26.                     redirected DIR command. For example, the DOS command 
  27.  
  28.                     dir *.txt >dirfile  ─┘
  29.  
  30.                     will create a disk file named "dirfile" which contains a 
  31.                     directory of all files with a ".TXT" extension.
  32.  
  33.                2.   "ext" is the filename extension you wish to assign each 
  34.                     output file. The output files are created using the name 
  35.                     of the input file plus the extension specified here. The 
  36.                     choice of an extension is important; if you accidentally 
  37.                     choose an extension which is already used by an input 
  38.                     file, the result of the process is indeterminable, 
  39.                     although file data loss is likely to occur. Use an 
  40.                     extension which is sure to be unique.
  41.  
  42.                     Extensions can be the DOS device names CON, NUL, AUX, and 
  43.                     PRN.
  44.  
  45.                3.   "tablename" is the unambiguous DOS path/file name which 
  46.                     contains the string translation "equations". Although no 
  47.                     restrictions are placed upon the tablename, for sake of 
  48.                     clarity it is suggested that you adopt a consistent naming 
  49.                     scheme for them, (say, with an *.SNR extension). Tables 
  50.                     are discussed in more detail below. 
  51.  
  52.                4.   "/d" is an option which replaces the original input file 
  53.                     with the converted data. The EXT specified on the 
  54.                     command line is thus used temporarily until the conversion 
  55.                     is complete, at which time the program performs an 
  56.                     internal file delete/rename operation. 
  57.  
  58.                EXAMPLES...
  59.  
  60.                C>snr tstfil.doc txt tst.snr ─┘
  61.  
  62.                The above command line will process some input file 
  63.                "tstfil.doc" and create an output file "tstfil.txt" using some 
  64.                table "tst.snr". 
  65.  
  66.                C>snr @dirlist p1 sample.snr ─┘
  67.  
  68.                The above command line will process some group of files 
  69.                contained in the directory list "dirlist" and create some group 
  70.                of output files with extensions of *.p1 using some table 
  71.                "sample.snr".
  72.  
  73.                TABLES...
  74.  
  75.                SNR tables are ASCII text files which contain the search-and-
  76.                replace equations used by the program. Up to 50 of these 
  77.                equations can be entered in a single table; each equation can 
  78.                consist of 70 characters on the search side, and 70 characters 
  79.                on the replacement side. Blank lines will be ignored by the 
  80.                table processor. A sample equation would be: 
  81.                
  82.                Now is the time=NOW IS THE TIME
  83.                
  84.                It should be obvious that this equation will translate an 
  85.                upper-and-lower case version of the words "now is the time" to 
  86.                an all-upper-case string. Notice that spaces ARE SIGNIFICANT 
  87.                characters in an equation. A search string can be defined to 
  88.                output nothing, simply by leaving out a replacement string:
  89.                
  90.                Now is the time=
  91.                
  92.                If spaces are desired at the end of a replacement string, they 
  93.                can be defined as hex codes:
  94.                
  95.                Now is the time =NOW IS THE TIME\20
  96.  
  97.                Any hex code can be formed from a backslash followed by two hex 
  98.                digits (0-9, a-f, A-F). For instance, a carriage return/line 
  99.                feed sequence can be specified like this: 
  100.                
  101.                \0d\0a\0d\0a=\0d\0a
  102.                
  103.                The above equation will convert two CRLFs in a row to a single 
  104.                CRLF. A consequence of the backslash notation is that the 
  105.                backslash itself must be specified in a string as \5c. 
  106.                Likewise, the equals sign must be specified in a string as \3d. 
  107.  
  108.                The null character (\00) is a special case. You should define 
  109.                it only as a single-character equation, to be converted to 
  110.                something else or ignored:
  111.  
  112.                \00=\20             \ convert NULL to SPACE
  113.  
  114.                Internal limitations of SNR prevent using the NULL character as 
  115.                part of a larger search string.
  116.  
  117.                The end of a table is signified by a \\E on a line by itself. 
  118.                This code is optional, but recommended, since it will prevent 
  119.                the table processor from inadvertently reading past the end of 
  120.                your equations (some word processors may pad their last blocks 
  121.                with garbage, which the table processor would attempt to read 
  122.                as equation data). 
  123.                
  124.                Comments can be entered in a table as lines by themselves, or 
  125.                set off from an equation:
  126.                
  127.                \    This is a comment line by itself.
  128.                \    A comment consists of a single backslash
  129.                \    followed by one or more spaces.
  130.  
  131.                \0d\0a=\0d\0a  \ this will ensure that existing CRLF pairs are
  132.                               \ left untouched
  133.                \0d=\0d\0a     \ this equation will convert an isolated CR 
  134.                               \ into a CRLF
  135.                \0a=\0d\0a     \ this equation will convert an isolated LF
  136.                               \ into a CRLF
  137.                
  138.                \\E
  139.  
  140.                Equation ordering is for the most part immaterial, except in 
  141.                the case where several search strings begin with the same 
  142.                character. For these occurrences, the strings must be ordered 
  143.                by length, longest search pattern to shortest (the above 
  144.                example demonstates this).
  145.  
  146.                See the sample tables for more clarification.
  147.  
  148. NOTES:         The program must reside in a subdirectory defined in a PATH 
  149.                command, or it must reside in the current subdirectory. (It 
  150.                reads itself for certain runtime parameters.)
  151.  
  152.                SNR will perform admirably when processing a table whose 
  153.                search-and-replace strings occur infrequently in a file. The 
  154.                greater the incidence of search matches, the slower the program 
  155.                will run. 
  156.  
  157. MACHINE:       The program will run on any IBM PC/XT/AT series computer using 
  158.                MS-DOS 2.x or higher, with a minimum of 128K RAM.
  159.  
  160. DISCLAIMER:    This program is distributed as user-supported software. Use 
  161.                it, copy it, give it to your friends. Please distribute the 
  162.                program in ARC form, including all document and sample files. 
  163.                No warranties, either expressed or implied, are given by the 
  164.                author or distributor of the program, and the user accepts all 
  165.                risk of damage arising out of the application and use of the 
  166.                program. 
  167.  
  168. BEG:           If you like the program, contributions in any amount ($10 
  169.                requested) will be gratefully accepted. Please make checks 
  170.                payable to Thomas A. Lundin.
  171.                
  172.                A search-and-replace utility that imposes none of the 
  173.                restrictions of SNR is available as a commercial program named 
  174.                SuperConverter. For $99, SuperConverter allows up to 1,600 
  175.                search-and-replace equations to be defined in a table, each of 
  176.                which can consist of up to 1,000 characters. SuperConverter can 
  177.                process files at speeds up to 30,000 cps on AT-class machines, 
  178.                although the nominal conversion rate is roughly 2,500 cps. 
  179.                SuperConverter supports wild card string matching, preprocessor 
  180.                setup definitions, and flag states in conversion strings. 
  181.                SuperConverter is an entirely different program from SNR; they 
  182.                share no program code. Commercial purchasers will receive a 
  183.                printed manual and sample tables. For more information, call me 
  184.                at the number listed below (8am-5pm Central Time, Mon-Fri). 
  185.  
  186.                Send comments/bug reports/contributions to:
  187.  
  188.                          ╔══════════════════════════╗
  189.                          ║     Thomas A. Lundin     ║
  190.                          ║ Graphics Unlimited, Inc. ║
  191.                          ║ 3000 Second Street North ║
  192.                          ║  Minneapolis, MN  55411  ║
  193.                          ║      (612) 588-7571      ║
  194.                          ╚══════════════════════════╝
  195.  
  196.                You can also reach me at my BBS home base:
  197.  
  198.                                 PC-ROCKLAND BBS
  199.                       If you can't find a program here,
  200.                           it probably doesn't exist!
  201.                                 (914) 353-2176
  202.                         (Leave msg. for "Tom Lundin")
  203.  
  204.                Thank you for using SNR.
  205.  
  206.